MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) where the menu item is created. If the menu does not exist, InsertMenuitem does nothing.
ItemNumber specifies the menu item number (from 1 to 255) where the item is inserted. If the menu item does not exist in the specified menu, InsertMenuitem does nothing. InsertMenuitem will append one item to the end of a menu if the ItemNumber equals the current number of items plus 1.
EnabledFlag specifies whether the item is enabled or disabled. In the enabled state, the item can be selected whereas in the disabled state, the item is dimmed and cannot be selected by the user. The two constants that can be used for this purpose are enabled and disabled. Menus and menu items can be enabled and disabled by using the EnableMenu procedure.
MenuText is the name of the item. Certain metacharacters are recognized by Tools Plus to provide special instructions to the Menu Manager. You may choose to include or exclude these characters within MenuText, however, you should be aware of their effects. See the Menu procedure for details on metacharacters.
When the item is inserted, all existing items starting at ItemNumber are pushed down one space to make room for the new item. This means that their item number will be changed. The new item is inserted at the location specified by ItemNumber. The main use for this procedure is to let your application maintain a dynamic menu, such as a list of open document names.
Note: The Macintosh’s Menu Manager allows only the first 31 items of a
menu to be disabled individually. The entire menu, however, can
always be disabled.
If a menu item that owns a submenu is disabled, either by
disabling the item individually or by disabling the entire menu,
the submenu cannot be viewed by the user.
Warning: The first two menus (File and Edit) are limited to 31 items
each. This limit has been imposed to ensure that an
application running under Finder (System 5 and 6) can adhere to
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that is affected. If the menu does not exist, RemoveMenu does nothing.
ItemNumber specifies the menu item number (from 1 to 255) that is deleted. If ItemNumber is zero (0), RemoveMenu refers to the menu’s name in the menu bar and all its associated items. If the menu item is not zero and it does not exist, RemoveMenu does nothing.
If a menu is deleted along with its associated items (i.e., when ItemNumber = 0), any menus with higher menu numbers are shifted to the left to fill in the space occupied by the deleted menu. Their menu numbers, however, remain unchanged. If the affected menu has submenus, those submenus are automatically detached but not deleted. If the affected menu is a submenu, it is automatically detached from its parent menu.
In order to prevent the menu bar from flickering each time a pull-down menu is removed, this procedure does not immediately display the altered menu bar. When you have finished making changes to the menu bar (by using the Menu and/or RemoveMenu procedures), call UpdateMenuBar to display the changes made to the menu bar.
Note: Use RemoveMenu to maintain a dynamic menu, such as a list of open
windows. Do not use it to make items unavailable. Instead,
Display the menu bar with the changes made by the Menu procedure, RemoveMenu procedure, or EnableMenu procedure (when enabling/disabling an entire menu).
pascal void UpdateMenuBar(void);
procedure UpdateMenuBar;
The UpdateMenuBar procedure is not performed automatically because the menu bar flickers slightly whenever it is updated. If several updates were to be performed in a row (by creating several new pull-down menus at the beginning of a program, for example, or enabling/disabling several menus), the repeated flicker would be quite annoying. The UpdateMenuBar procedure should be called when your application is finished creating, deleting, or enabling/disabling pull-down menus. UpdateMenuBar automatically resets a highlighted menu in the menu bar. Changes made to individual menu items or to hierarchical menus do not require a call to UpdateMenuBar.
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) containing the required menu item.
ItemNumber specifies the menu item number (from 1 to 255) from which the text is obtained.
MenuText specifies the menu item’s name. If the specified menu number or item number doesn’t exist, MenuText returns as a null string (length is zero). Note that the string will return as a single space (‘ ’) if a null string was specified when the item was created (this happens automatically to prevent the Menu Manager from crashing).
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) in which the menu item is changed. If the menu number does not exist, RenameItem does nothing.
ItemNumber specifies the menu item number (from 1 to 255) which is changed. If the item number does not exist within the menu specified by MenuNumber, RenameItem does nothing.
MenuText specifies the menu item’s new name. MenuText may be blank, but should never be a null string. The item’s state (enabled/disabled), style (bold, underline, etc.), icon and Command key equivalent are not changed. Metacharacters are not interpreted by this procedure.
RenameItem does not change the menu’s name in the menu bar. If the menu’s name must be changed, the affected menu must be removed with the RemoveMenu procedure, then re-created as required by using the Menu procedure.
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) in which the enabling/disabling will take place. If the menu number does not exist, EnableMenu does nothing.
ItemNumber specifies the menu item number (from 1 to 255) which is enabled/disabled. A value of zero (0) affects the entire menu. If ItemNumber is not zero and the item number does not exist within the menu specified by MenuNumber, EnableMenu does nothing.
EnabledFlag specifies whether the menu/item is enabled or disabled. In the enabled state, the menu/item can be selected. In the disabled state, the menu/item is dimmed and cannot be selected by the user. The two constants that can used for this purpose are enabled and disabled. If the ItemNumber is zero, the disabling of the menu applies to all items within that menu. When the menu later becomes enabled, all items in the menu assume their correct enabling/disabling as specified by your application. In a disabled pull-down menu, the name in the menu bar is dimmed along with all its items. In a hierarchical menu, all the items in the submenu are dimmed and cannot be selected.
You can enable or disable the entire Apple menu by specifying zero for both the menu number and item number.
This procedure does not change the menu bar if any of the pull-down menus are enabled/disabled by using an ItemNumber equal to zero (0). This is done to prevent the menu bar from flickering each time a menu is enabled or disabled. When you have finished making changes to the menu bar (by using the Menu, RemoveMenu, or EnableMenu procedures on pull-down menus) call UpdateMenuBar to display the changes made to the menu bar.
Note: The Macintosh’s Menu Manager allows only the first 31 items of a
menu to be disabled individually. The entire menu, however, can
always be disabled.
If a menu item that owns a submenu is disabled, either by
disabling the item individually or by disabling the entire menu,
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that is affected. If the menu number does not exist, CheckMenu does nothing.
ItemNumber specifies the menu item number (from 1 to 255) that is affected. If the item number does not exist within the menu specified by MenuNumber, or if this item owns a submenu, CheckMenu does nothing.
Checked specifies whether the menu item’s check mark is displayed or hidden. The two constants that can be used for this purpose are on and off.
To display characters other than the standard check mark, use the MenuMark procedure.
Display or hide a special character to the left of a menu item’s name. Use this procedure instead of CheckMenu to display or hide characters other than the standard check mark.
pascal void MenuMark (short MenuNumber, short ItemNumber,
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that is affected. If the menu number does not exist, MenuMark does nothing.
ItemNumber specifies the menu item number (from 1 to 255) that is affected. If the item number does not exist within the menu specified by MenuNumber, or if this item owns a submenu, MenuMark does nothing.
MarkChar specifies the character that is to be displayed. The following constants are available for menu marks:
CONST {Menu Item characters }
AppleChar = char($14); {Apple character }
CheckChar = char($12); {Check Mark character }
DiamondChar = char($13); {Diamond character }
DotChar = char($A5); {Dot (or bullet) character }
NoChar = char($00); {no character (remove a character) }
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that contains the desired menu item.
ItemNumber specifies the menu item number (from 1 to 255) whose mark character is obtained.
MarkChar contains the “mark” character that is displayed to the left of the item’s name. If no mark is displayed by the specified menu item, or if the specified menu or menu item doesn’t exist, MarkChar is set to null (char(0)). The following are useful constants for testing menu marks:
CONST {Menu Item characters }
AppleChar = char($14); {Apple character }
CheckChar = char($12); {Check Mark character }
DiamondChar = char($13); {Diamond character }
DotChar = char($A5); {Dot (or bullet) character }
NoChar = char($00); {No character (remove a character) }
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that is affected. If the menu number does not exist, MenuCmd does nothing.
ItemNumber specifies the menu item number (from 1 to 255) that is affected. If the item number does not exist within the menu specified by MenuNumber, or if this item owns a submenu, MenuCmd does nothing.
CmdChar specifies the menu item’s Command-key keyboard equivalent. For consistency, use upper case letters (shifted characters are ignored, so Command-+ is interpreted as Command-=). Do not use Control characters, since older Macintosh keyboards such as those found on the Macintosh Plus don’t have a Control key. Tools Plus prevents you from using characters $1B through $1F (Control-[, Control-\, Control-], Control-Up Arrow, and Control--), because these characters are reserved by Apple for the system’s use.
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that contains the desired menu item.
ItemNumber specifies the menu item number (from 1 to 255) whose Command-key character is obtained.
CmdChar contains the item’s Command-key character. If the menu item doesn’t have a Command-key equivalent, or if the specified menu or menu item doesn’t exist, cmdChar is set to null (char(0)). This is the case if the menu item owns a submenu.
Note: A command key cannot be assigned to a menu item if it has a
submenu or if it displays an SICN icon. This is a limitation
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that is affected. If the menu number does not exist, MenuIcon does nothing.
ItemNumber specifies the menu item number (from 1 to 255) that is affected. If the item number does not exist within the menu specified by MenuNumber, MenuIcon does nothing.
IconSelector identifies the icon that is used, and should be from 1 to 255. The Menu Manager adds 256 to the number you state to specify a resource ID that is in the range of 257 to 511, so if you specify 28, resource ID 284 is used (28 + 256 = 284). These icon resources are read from your application. If Color QuickDraw is available on the Macintosh running your application, a ‘cicn’ (color) icon is used. If a ‘cicn’ is not available (or Color QuickDraw is unavailable), an ‘ICON’ or ‘SICN’ is used. Use zero (0) if you don’t want an icon displayed.
Unlike the equivalent Macintosh toolbox routine, your menu item will remain unaffected if the specified icon can’t be found (i.e, empty space is not reserved in the menu).
Be aware that the Menu Manager drawing a ‘cicn’ icon in color will do so even if the icon was created using 8-bit colors and the monitor is set to 4-bits. This may produce unsatisfactory results. If possible, use 4-bit colors or colors that translate well into 4-bit colors.
Note: Due to limitations imposed by the Macintosh’s Menu Manager,
assigning an ‘SICN’ icon to a menu item clears the command key for
that item. Also, an ‘SICN’ icon can’t be assigned to a menu item
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that contains the desired menu item.
ItemNumber specifies the menu item number (from 1 to 255) whose icon number is obtained.
IconSelector contains the item’s icon number. The Menu Manager automatically adds 256 to the IconSelector you specify, so an IconSelector of 28 means that resource ID 284 is used (28 + 256 = 284). If an icon is not displayed by the specified menu item, IconSelector is equal to zero.
MenuNumber specifies the menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) that is affected. If the menu number does not exist, MenuStyle does nothing.
ItemNumber specifies the menu item number (from 1 to 255) that is affected. If the item number does not exist within the menu specified by MenuNumber, MenuStyle does nothing.
TheStyle specifies the style(s) in which the menu item is to be displayed. Special character constants defined by the Font Manager are bold, italic, underline and shadow. C programmers will use the font manager’s constants to specify a composite style, such as MenuStyle(1,1, bold + outline) for bold and outlined, or MenuStyle(1,1,0) for plain text. Pascal programmers will use the font manager’s constants to specify a set, such as MenuStyle(1,1,[bold,outline]) for bold and outlined, or MenuStyle(1,1, [ ]) for plain text.
pascal void GetParentMenu (short *MenuNumber, short *ItemNumber,
short SubMenuNumber);
procedure GetParentMenu (var MenuNumber: INTEGER;
var ItemNumber: INTEGER; SubMenuNumber: INTEGER);
A hierarchical menu can be attached to a pull-down menu or to another hierarchical menu. When attaching a hierarchical menu to a “parent” (or if you prefer to view it the other way, providing a “parent” menu with an “offspring” hierarchical menu), the owner of the submenu is called a “parent” menu, and this routine is used to determine a parent menu and item number for a known submenu.
MenuNumber contains the “parent” menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) which owns the specified submenu. If the specified submenu does not exist, or if it is not attached to a parent menu, MenuNumber is set to zero (0).
ItemNumber contains the menu item number (from 1 to 255) which owns the specified submenu. If the specified submenu does not exist, or if it is not attached to a parent menu, ItemNumber is set to zero (0).
SubMenuNumber specifies a hierarchical menu number (from 16 to 200) being queried. If the specified menu does not exist, MenuNumber and ItemNumber will both return with zero (0) values. You can specify a pull-down menu number (from 1 to 15), but its parent menu and item number will always return with a value of zero (0).
A hierarchical menu can be attached to a pull-down menu or to another hierarchical menu. When attaching a hierarchical menu to a “parent” (or if you prefer to view it the other way, providing a “parent” menu with an “offspring” hierarchical menu), the owned hierarchical menu is called a “submenu,” and this routine is used to determine a submenu for a known parent menu and item number.
MenuNumber specifies the “parent” menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) being queried.
ItemNumber specifies the menu item number (from 1 to 255) being queried.
SubMenuNumber returns with a hierarchical menu number (from 16 to 200) which is the submenu for the specified MenuNumber and ItemNumber. If the menu specified by MenuNumber does not exist, or if the specified ItemNumber does not exist within the menu, SubMenuNumber returns with a value of zero (0). SubMenuNumber also returns with a value of zero (0) if the specified menu and item do not own a submenu.
Highlight a menu in the menu bar, or remove the current highlight from the menu bar.
pascal void MenuHilite (short MenuNumber);
procedure MenuHilite (MenuNumber: INTEGER);
MenuNumber specifies the pull-down menu number (from 1 to 15) that is highlighted. Since only one menu can be highlighted at a time, any other highlighted menu is automatically unhighlighted. Specifying a MenuNumber of zero (0) unhighlights the currently highlighted menu. If the menu number does not exist and is not zero (0), MenuHilite does nothing.
